.NET Report Engine Configuration File Reference

The article details how to name the .NET Engine configuration file, and its contents.

app.exe.config

In the .NET environment, we are encouraged by Microsoft to use a configuration file rather than the Windows Registry for settings and values. The advantage to this is you can use config files to copy all files to a new location without requiring the migration of a bunch of different settings and values in the Registry.

The name and location of these files is set by Microsoft and cannot be overridden (it is different for Office Add-Ins such as Report Designer). The schema for the config (XML) file is also specified by Microsoft.

For an ASP.NET application, the config file is named ‘web.config’ and goes in the root directory of the website.

For a program named "RunReport.exe" the file is labeled "RunReport.exe.config". This must be in the same directory as RunReport.exe. If you rename "RunReport.exe" to "MyCoolApp.exe", then you need to also rename the config file "MyCoolApp.exe.config". The common shorthand for the config file is "app.exe.config", but that is not its actual name (unless your application is named "app.exe", which is unlikely).

Sample app.exe.config File

We provide a sample config file named ‘WindwardReports.dll.config’ with .NET Report Engine, but a config file with that name is not used by .NET Report Engine. Please do not try to use a file with this name.

Below is a sample config file with the minimum required settings for .NET Report Engine. At a minimum, your license key must go in this file. .NET Report Engine will not look in the registry for the license key; it must be in the config file. Generally (definitely in the case of an ASP.NET app), you will have additional sections in this file.

Although not required, we've included a logging section in the sample app.exe.config, since logging is used so often by embedding-application developers and Support for troubleshooting.

<?xml version="1.0" encoding="utf-8" ?>
   <configuration>
      <configSections>
         <section name="WindwardReports" type="System.Configuration.NameValueSectionHandler"/>
         <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,log4net, Culture=neutral, PublicKeyToken=669e0ddf0bb1aa2a" />
      </configSections>  
      <WindwardReports>
         <!-- Put your key here. Multiple lines are ok but do not put spaces at the beginning/end of the lines -->
         <add key="license" value="the/license/goes/here"/>
      </WindwardReports>

      <log4net debug="false">
         <appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
            <!-- This specifies where the file will be written. Make sure your app has write permissions to this folder! -->
            <param name="File" value="C:\temp\LoggingExample.log" />
            <param name="AppendToFile" value="true" />
            <!-- When a file is filled it is renamed LoggingExample.log.1 and a new LoggingExample.log is created. -->
            <param name="MaxSizeRollBackups" value="10" />
            <!-- MaxSizeRollBackups * MaximumFileSize determines how much recent logging is retained. -->
            <param name="MaximumFileSize" value="50KB" />
            <param name="RollingStyle" value="Size" />
            <param name="StaticLogFileName" value="true" />
            <layout type="log4net.Layout.PatternLayout">
               <!-- When sending a log to Windward, we need all of these values, but you can change the order. -->
               <param name="ConversionPattern" value="%date [%thread] %level %logger - %message%newline%exception" />
            </layout>
         </appender>
         <root>
            <!-- Normally set to info or warn. When providing to Fluent set to debug. -->
            <level value="debug" />
            <appender-ref ref="RollingFileAppender" />
         </root>
      </log4net>
   </configuration>

Log File Not Created?

Having problems with your log file not being created? To address that:

If you configured logging in your app.exe.config file and you find that there is no log file created, make sure you have permissions to write to the location you specified in app.exe.config.

If that doesn't resolve the issue, try putting the following code in your application before your logging code: log4net.Config.XmlConfigurator.Configure();

You can define it in Global.asax:

void Application_Start(object sender, EventArgs e)
{
    // Code that runs on application startup
    // Initialize log4net.
    log4net.Config.XmlConfigurator.Configure();
}

You can also add the following line (either mentioning your config file name or not):

[assembly: log4net.Config.XmlConfigurator]

Or

[assembly: log4net.Config.XmlConfigurator(ConfigFile = "Web.config", Watch = true)]

Additional Logging Info

If you would like additional logging info with your exceptions such as the InnerException and the StackTrace, you can use Windward's custom log format layout. To use this, replace the current <layout> block within the <log4net> block in app.config and replace it with this.

If you would like to use the ExceptionFormatter class in other applications, you can get it here.

<layout type="Kailua.net.windward.utils.ExceptionFormatter" >
    <param name="Pattern" value="%date [%thread] %level %logger - %exception%newline" />
</layout>

To have log4net see this class, you need to initialize it in your code as follows:

// by loading this, log4net sees it  

Using the <log4net> section from above, the modified version would look like

<log4net debug="false">
      <appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
         <!-- This specifies where the file will be written. Make sure your app has write permissions to this folder! -->
         <param name="File" value="C:\temp\LoggingExample.log" />
         <param name="AppendToFile" value="true" />
         <!-- When a file is filled it is renamed LoggingExample.log.1 and a new LoggingExample.log is created. -->
         <param name="MaxSizeRollBackups" value="10" />
         <!-- MaxSizeRollBackups * MaximumFileSize determines how much recent logging is retained. -->
         <param name="MaximumFileSize" value="50KB" />
         <param name="RollingStyle" value="Size" />
         <param name="StaticLogFileName" value="true" />
         <layout type="Kailua.net.windward.utils.ExceptionFormatter" >
             <param name="Pattern" value="%date [%thread] %level %logger - %exception%newline" />
         </layout>
      </appender>
      <root>
         <!-- Normally set to info or warn. When providing to Fluent set to debug. -->
         <level value="debug" />
         <appender-ref ref="RollingFileAppender" />
      </root>
   </log4net>

Optional Settings

See .NET Report Engine app.exe.config Settings for all of the optional settings that can be added to app.exe.config.